fix(metadata-protocol): stop persisting derived provenance keys, and restate tenant authorship at hydration for every type - #16796

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 5 documentable anchor(s).

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/deployment/validating-metadata.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/kernel/cluster.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/kernel/services-checklist.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/permissions/authorization.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 2037782843f0518a1c34791c0aad98e0acb892ed && git checkout 2037782843f0518a1c34791c0aad98e0acb892ed
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 625b0c32b4431ba5c04d7f898152a03a1f8a0251 e50b911ab90943da338b4151d5a4ac97c24653de && git checkout -B drift-repro 625b0c32b4431ba5c04d7f898152a03a1f8a0251 && git merge --no-ff e50b911ab90943da338b4151d5a4ac97c24653de

node scripts/docs-audit/affected-docs.mjs --json 625b0c32b4431ba5c04d7f898152a03a1f8a0251

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 625b0c32b4431ba5c04d7f898152a03a1f8a0251 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review (CONTRACT_REVIEW_TIER, isolated seat) — PR #16796 @ bbe4590c0

Verdict: CHANGES REQUIRED

Ruling implemented: no ruling — no maintainer ## Ruling recorded exists on card #16702 or on this PR. The PR implements the triage seat's preference (os-zhuang, 5578409434: "建议两条都做") as adopted by the PM seat (5578971143), which the card itself left open as "Which one — or both — is a maintainer call." Both seats explicitly declined the decision box on the "zero-cost narrowing" argument. The only maintainer ruling this PR cites is the batch #35 WHICH LEVEL ruling (.github/workflows/pr-automation.yml:667-682), which governs the changeset level, not the fix shape — and the PR's level choice is where it breaks (F1).

Quoted verbatim, the closest thing to a ruling on the card (triage, seat preference, not maintainer):

而且两条修法不互斥，卡面自己也这么说（"which one — or both"）：(1) 让存量语料向读侧已经在重算的那个真相收敛，(2) 让今天已经写坏的行在不重写的情况下无害。建议两条都做，理由是它们覆盖的是不同的时间窗

Scope vs that preference: exactly — both doors, three keys only, _lock* untouched, object branch source untouched (the only three non-comment code lines that change in protocol.ts are stripDerivedProvenance at the write door, stateTenantAuthorship inside hydrateOverlayIntoRegistry, and the two module-private helpers).

1. Files in the diff vs merge-base 8b37a0973d (6 files, +604/−8)

Governed paths touched: NO (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, content/docs/releases/** — none). The documentation / tooling labels are the auto-labeler's, not a governed touch. Maintainer-only merge on governed grounds: no.

2. Clause-② re-derived independently: yes — and the body's own patch argument contradicts its own declaration

Re-derived from code, not from the body:

• Persisted metadata shape narrows. saveMetaItem (protocol.ts:15006) now drops _packageId / _packageVersion / _provenance from every body it persists, for every type including object (the strip sits before the type branch). The stored sys_metadata body is a persisted shape; it changed.
• Hydrated registry-entry shape widens. hydrateOverlayIntoRegistry (:14131) now registers {...data, _provenance: 'org'} for every non-object row with no artifact. That entry is what SchemaRegistry.getItem / getAllApps / listItems answer — an exported objectql surface — and the PR's own six updated deep-equality pins are the measurement of that change.
• The accept set of PUT /meta/TYPE/NAME is unchanged (the three keys are still accepted and silently dropped), so the request contract is not narrowed.

⇒ Clause-②: yes is correct. The body's argument that the act is "the opposite of additive" and therefore patch is where it goes wrong: the WHICH LEVEL ruling says a fix( that changes no public surface stays patch; this PR declares — correctly — that it changes one.

3. Changeset

• Package name @objectstack/metadata-protocol: correct (the only package whose src/** moves; it is in the fixed group, version 17.3.0, not private).
• Level patch: wrong per the gate that enforces the batch [WIP] Add query enhancements and advanced validation features #35 ruling — see F1. scripts/check-changeset-no-major.mjs judgeLevel: "enforce — declared yes, patch on a grown package → exit 1". Both Check Changeset runs on the head are red on exactly this.
• No **BREAKING** banner and no ADR-0087 disposition: correct — nothing an author can write is removed or renamed; check-adr-0087-registration passes.
• FROM/TO: the body states what stops being persisted and what is restated; it does not state the served-document residual (F2). Nothing deliberately removed is silently dropped.

4. Tests

• New file protocol-derived-provenance-doors.test.ts: real ObjectQL + real SchemaRegistry + stub driver (not an engine double). No .skip / .only / .todo / skipIf in any of the four changed test files.
• Would redden on revert, reasoned from code: the door-1 pins assert not.toHaveProperty('_packageId'|'_packageVersion'|'_provenance') on the stored body; without stripDerivedProvenance the repository's put persists JSON.stringify(body) verbatim (sys-metadata-repository.ts:666) → red. The door-2 pins seed a row with _provenance: 'package' and assert the hydrated entry is 'org'; without stateTenantAuthorship the hydrator registers data as-is → red. The repro leg: with both doors absent, isCodeArtifactBody (metadata-core/src/code-artifact-provenance.ts) accepts truthy non-sentinel _packageId + non-org provenance, getArtifactItem's bare-key fallback (registry.ts:3759/3777) returns the overlay, NOT_OVERRIDABLE follows → red. Not vacuous.
• Negative control (criterion 3) registers a real artifact under the composite key and asserts 403 both without and with a hydrated overlay: it discriminates an "unconditional allow" implementation.
• Criterion 5 asserts every artifact envelope key wins over both the stored copy and the 'org' stamp — the ordering contract of door 2 is pinned.
• Typecheck program: packages/objectql/tsconfig.test.json includes src/**/*; the new file has no entry in the shrink-only debt ledger, so it must compile at zero errors — Type Check · workspace is green on the head.
• Caveat the body admits: the suite resolves @objectstack/metadata-protocol through dist/, so locally it reddens only after a rebuild. CI orders Build Core before Test Core, so the gate is real there.

5. Persistence / hydration specifics

• Stops being persisted: exactly _packageId, _packageVersion, _provenance, on the saveMetaItem door only, for all types (object included). _lock / _lockReason / _lockSource / _lockDocsUrl are persisted unchanged (pinned).
• Restated at hydration: _provenance: 'org' on a copy, for every non-object row reaching hydrateOverlayIntoRegistry (boot loadMetaFromDb, read-side getMetaItems on the unscoped kernel, and the meta overlay: a just-saved overlay is listed but not dispatchable for a short window — a cache between saveMeta and resolveRouteActionDeclaration lags the write #4521 write-through), applied before mergeArtifactProtection so an artifact's _provenance/_packageId/_packageVersion/_lock* still overwrite it. The object limbs (applyObjectRegistryMutation, boot registerObject branch) are byte-for-byte untouched.
• Backward read compatibility: a row written before this PR still parses and still hydrates (no schema change, no migration of at-rest bytes). It does not hydrate identically: its registry entry's _provenance becomes 'org' where it was previously the stored value or absent — that is the fix, and the six updated pins are the measurement. But the served document for an at-rest poisoned row is not corrected by this PR — see F2. That is a backfill question, not a migration of this PR, and it must be stated.

6. Criterion-6 reading, spot-checked

The body's claim that getMetaItems re-stamps _packageId from the package_id column onto the body handed to the hydrator is confirmed at :7288-7290 ((data as any)._packageId = recPkg) → :7380 (hydrateOverlayIntoRegistry). Door 1 cannot reach it; door 2 makes it non-load-bearing because isTenantAuthored asks _provenance, not _packageId. The "both doors are not redundant" reasoning holds.

7. CI on head bbe4590c0

37 check runs: 29 success · 2 failure · 6 skipped · 0 in progress. Red: Check Changeset ×2 (pr-automation on opened and on labeled), both on the level axis above. Skipped: Packed-tarball smoke ×2 (opt-in), Auto Label, Check PR Size, Build Docs, Console Pin Gate. mergeable_state: unstable (the red gate). Head is 11 commits behind origin/main at review time (base recorded at CI: b38821d1; merge-base now 8b37a097). No reviews on the PR; one bot comment (docs-drift, advisory).

Findings

F1 — CHANGES REQUIRED. Changeset level patch is refused by the gate that enforces the batch #35 ruling, and the refusal is correct. The PR declares Clause-②: yes (and carries the needs:contract-review carrier) while grading @objectstack/metadata-protocol patch; check-changeset-no-major.mjs judgeLevel returns enforce, exit 1 — both Check Changeset runs are red. This seat's independent re-derivation agrees the surface changes (persisted body narrows; hydrated registry-entry shape widens). Expectation: take the gate's route 1 — change the one word in .changeset/derived-provenance-write-door-and-hydration.md to minor, and rewrite the body's "Changeset" paragraph so it no longer argues patch from "not additive" while declaring yes. ⛔ Do not take route 2 (flipping the declaration to no) — the declaration is the accurate half.

F2 — Must be stated in the PR body and changeset: door 2 corrects the authorization verdict, not the served document. getMetaItem step 1 (:7860-7875) serves the raw overlay row body with only _packageId stamped from the column and no _provenance restatement; mergeArtifactProtection only fires when an artifact exists. getMetaItems likewise serves the overlay data (which wins the merge over the restated registry entry). So a row poisoned at rest keeps being served as _provenance: 'package' by GET /meta/app/x — the UI keeps badging it as package-provided — until the row is re-saved (door 1) or backfilled by cloud#2069 / cloud PR #2111. The refusal is gone; the misattribution in the served body is not, for that population. Expectation: one sentence in the changeset and the body naming this residual and that the cloud backfill is load-bearing for it; carry it into the criterion-7 reply on cloud#2069 so cloud does not read "door is shut" as "backfill no longer needed".

F3 — Non-blocking, confirm the body's "noted, not filed" is complete. promoteDraft (:16942) and restoreVersion (rollbackMetaItem :20331, revertCommit :19941) hand a stored draft/history body straight to repo.put without stripDerivedProvenance. A rollback to a pre-PR history version therefore re-persists the three keys into the active row. Door 2 keeps that harmless for hydration; the corpus does not converge on those doors. Expectation: acceptable as scoped, but the body's claim "door 1 covers them transitively" is only true for bodies written after this PR — say so.

F4 — Minor. Door 2 restates only _provenance; a poisoned row's stale _packageVersion survives onto the hydrated entry (non-load-bearing for authorization, cosmetic until backfill). Expectation: none beyond F2's sentence.

F5 — Minor test gap. The strip is type-agnostic, so object bodies also lose the three keys at rest; the criterion-4 object case writes _packageId/_provenance into the request but asserts only the hydrated entry, not the stored body. Expectation: optional one-line not.toHaveProperty on the stored object row, so the type-agnostic scope of door 1 is pinned rather than implied.

F6 — Process, not a defect. The "both doors" decision was taken by triage + PM as a determinacy call, with an explicit invitation to rebut; the card's own text called it a maintainer call. This seat finds the determinacy argument sound (a stored copy is never load-bearing on the read side; only the lie is negated) and the ablation reasoning that the two doors cover different populations verified from code. Expectation: none — recorded so the maintainer sees the decision was a seat's, not theirs.

Summary for the maintainer: the fix is exactly what was dispatched, the pins discriminate, no governed path is touched. The single blocker is one word in the changeset (F1); F2 is a required disclosure, not a code change.

Generated by Claude Code

CI is green on a35c00ffa2 — and this PR is still ⛔ NOT landing. Both halves measured.

③ Every check green. On head a35c00ffa2: 12 workflow runs, PR Automation success, CI success, Lint & Type Check success, every guard success, one skipped (Pack Smoke, opt-in). Zero failures, zero in_progress. The three PR Automation failures on this branch are all on the superseded head bbe4590c0e ⇒ stale readings, zero-action, ⛔ never re-run.

The level-axis red is closed exactly as the gate's route 1 prescribes: @objectstack/metadata-protocol patch → minor, with the red reproduced offline at CI's own base and the green taken on the committed tree (the gate reads the HEAD tree, not the working directory).

⛔ Why green is not enough here

The contract review on this PR (5580303475) raises F2, F3 and F5 alongside F1. Only F1 was in scope for the changeset round and only F1 is discharged. ⇒ this is a patch round in progress, ⛔ not a PR awaiting a merge button. Landing it now would ship a diff whose own review says changes are required.

That is a documented blocker, ⛔ not a substitute for an attempt: the attempt was made — the red was diagnosed from the job log, fixed, and verified green — and what remains is work, not waiting.

Next: the F2/F3/F5 patch round is queued behind a free dispatch slot; #16783's equivalent round is in flight now.

⚠️ Two things this seat is deliberately NOT doing on a guess

1. The carrier. feat(engine)!: findOne, update and delete declare what they answer, and their hook seams are guarded (#16231) #16783's handoff ends with an instruction addressed to the seat — "carrier removed from card and PR (review concluded); re-hang both with the patched head" — and this seat has discharged it there. ⛔ It has not read this PR's handoff, so it is ⛔ not re-hanging needs:contract-review here by analogy. If this review concluded the same way, the re-hang is owed and the patch-round dev will surface it from the document itself. ⛔ A seat act inferred from a sibling is exactly the error class that produced a wrong order on feat(engine)!: findOne, update and delete declare what they answer, and their hook seams are guarded (#16231) #16783 this hour.
2. The body's missing attribution footer. The dev followed AGENTS.md's prescription for an edited body — send it without a footer, the platform appends one — and the platform did not append. It ⛔ did not re-send, because re-sending a body that already carries an appended footer is forbidden and a delayed async append would leave two. AGENTS.md is a governed surface ⇒ ⛔ reported, not edited. This needs a governed-surface decision from someone who can make one; attribution survives meanwhile in the pushed commit trailers.

⚠️ Standing debt on this card, unchanged: at landing, the "door is shut" reply is owed on objectstack-ai/cloud#2069. ⛔ cloud is not attached to this session and repo-scoped REST answers 403 ⇒ that half must be handed to a seat that can reach it, and this seat says so rather than letting both sides assume the other has it.

Generated by Claude Code

Contract review (claude-fable-5-1, isolated seat) — PR #16796 @ e50b911ab

Verdict: PASS

Re-review of a moved head. Prior review: 5580303475 @ bbe4590c0 (CHANGES REQUIRED, F1–F6). Since then: a35c00ffa2 (F1, changeset level) and e50b911ab9 (F2 / F3 / F5 patch round). Everything below is re-measured on refs/pull/16796/head = e50b911ab90943da338b4151d5a4ac97c24653de against merge-base 8b37a0973d with origin/main; nothing is taken from the PR body.

Ruling implemented: no ruling — unchanged. Card #16702 carries no maintainer ## Ruling recorded; the only "maintainer" text on the card is triage quoting the card's own "which one — or both — is a maintainer call" and declining the decision box on the zero-cost-narrowing argument (5578409434), adopted by the PM seat (5578971143, "executing triage … (both fixes)"). F6 stands as recorded.

Prior findings

Patch round bbe4590c0..e50b911ab — every file

.changeset/derived-provenance-write-door-and-hydration.md   | 4 (+3/−1)  patch→minor, F2 paragraph
packages/objectql/src/protocol-derived-provenance-doors.test.ts | 18 (+17/−1)  F5 pin

Two files, nothing else. No protocol.ts change in the patch round — the source under review is byte-identical to what 5580303475 read (stripDerivedProvenance :1214, stateTenantAuthorship :1248, call sites :15006 / :14131, DERIVED_PROVENANCE_KEYS :1195). The PR body edits are not in the tree. Full diff vs merge-base is still 6 files, +622/−8, same set as the prior review.

Governed paths touched: NO — docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, content/docs/releases/**: none in git diff --name-only 8b37a0973d..e50b911ab.

Clause-②: yes — stands as re-derived last round (persisted sys_metadata body narrows by three keys for every type; hydrated non-object registry entry widens by _provenance: 'org'). Level minor now matches the declaration. No **BREAKING** banner and none owed: check-adr-0087-registration's breakingDeclaration fires on major / **BREAKING / a type!: summary — the changeset has none of the three, and the job that runs it (pr-automation.yml:867-869, inside Check Changeset) is green on this head.

CI / merge state on e50b911ab

40 check runs: 34 success · 0 failure · 6 skipped · 0 in progress (skipped: Packed-tarball smoke ×2 opt-in, Auto Label and Check PR Size on the labeled re-run, Build Docs, Console Pin Gate). mergeable_state: clean. Head is 8 commits ahead / 78 behind origin/main (the base recorded on the PR, b38821d1, is older than the current merge-base) — the queue will re-merge; nothing in the diff overlaps a moving file that I can see, and No other open PR may claim the same single-writer path is green. Commit trailers: none of the 8 commits carries Fixes / Refs / Part of (the head commit's "F5 of the contract review on PR #16796" is prose, not a card-relation spelling); Part-of PR must not also close its card (RULE 2) is green ×2. Body carries Fixes #16702 and the PR is still draft, not queued, no auto-merge.

New findings (this round)

1. Non-blocking, owed item — criterion 7 is still open and belongs to a seat with cloud reach. The reply on objectstack-ai/cloud#2069 ("door is shut; the backfill stays load-bearing for rows poisoned at rest — see the F2 residual") has not been posted; the PM seat recorded it as owed at landing (5579975456) and objectstack-ai/cloud is not attached to any session that has worked this branch. Expectation: the director seat routes it to a seat with cloud attached, to post after this PR lands; the sentence must carry the F2 residual so cloud does not read "door shut" as "backfill retired". Not a merge condition of this PR.
2. Process, non-blocking — the PR body has no attribution footer. Confirmed: the body on this head ends at "Draft only. Not ready, not queued, no auto-merge." with no --- / _Generated by …_ block. AGENTS.md ("Write the attribution footer…", the PR body paragraph) prescribes the form and says "Durable attribution lives in body prose or a comment" and ⛔ "never re-send a body that already carries an appended footer" — it does not make a missing footer a merge condition, and the body carries none, so a single re-send with the session-URL form is permitted but not owed by the rule. Attribution is present in all 8 commit trailers (Claude-Session: + the harness Co-Authored-By, the one exemption the same paragraph names). Expectation: none for merge; the maintainer may re-send the body once with the session-URL footer if they want it stored.
3. Nit, optional. The new object pin's "nothing else was taken" line is toMatchObject({ name, label }), which cannot see an unexpected extra key on the stored row; the door-1 pins use the same shape, so this is consistent rather than a gap. Expectation: none; a toEqual against the exact stored shape would be strictly stronger if anyone touches the file again.

Maintainer-only merge: no

Grounds, on the whole picture rather than the governed axis alone: no governed path moves; no **BREAKING**, no !, no removed or renamed surface, no at-rest migration (a revert of this PR restores the previous behaviour byte-for-byte — rows written in between merely lack three keys the read side recomputes anyway); the minor bump is the declaration-driven floor, not a semver signal of widened API. The one open process point, F6, is a fix-shape decision the card handed to the maintainer and a seat took on a determinacy argument; that argument (a stored copy is never load-bearing for the authorization verdict; only the lie is negated) has now been verified from code twice, the F2 disclosure states precisely what the seat's choice does not fix, the rebuttal invitation on the card is still open, and the needs:contract-review carrier under Clause-②: yes — the compensating control for a low-tier dispatch — has been discharged by this review. Nothing here rises to the level that makes a merge maintainer-only; the decision stays visible to the maintainer on the card and in F6, which is what the record needs.

Generated by Claude Code

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 34249206284 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Dogfood Verify CLI — 失败步骤: Publish this leg's attestation（日志不可读，点进 job 看）

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• ⚠️ 本次没有可用的聚合签名（日志里没有能解析出测试文件名的 FAIL 行）—— 这不是「没有同签名的其他 PR」，是这一轮没测到。跨 PR 聚合本次不可用，请手工比对其他 PR 的同类评论。
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 0 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)